home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / mint / lib / mntlib44.zoo / mntlib / README < prev    next >
Text File  |  1994-03-01  |  8KB  |  167 lines
  1. This is the readme for the MiNT library.
  2.  
  3. To use the library you will nead the header files in mntincNN.zoo (where NN
  4. is the same patchlevel as the version of the library you're using).
  5.  
  6. As of patchlevel 26, Eric R. Smith has turned over maintenance of the library
  7. to me (entropy).  Like Eric, I only have GCC, so I've recruited a few people
  8. to act as sub-maintainers for the portions of the library I can't test.
  9.  
  10. Here are the maintainers' addresses:
  11. GNU C and common files:  entropy@terminator.rs.itd.umich.edu (Nick Castellano)
  12. Sozobon C/HSC:  dsb@cs.duke.edu (D. Scott Bigham)
  13. Pure C:  hohmuth@freia.inf.tu-dresden.de (Michael Hohmuth)
  14. Lattice C:  pvt1-117@nada.kth.se 
  15.  
  16. Be sure to read the "Changelog" file so that you know what's new in this
  17. release of the library.
  18.  
  19. Also, please read the "Copyright" file for important copyright information
  20. concerning some modules in this library.  Some modules, as noted in
  21. "Copyright", are covered by the GNU General Public License, which you will
  22. find in the file "GNUGPL2".
  23.  
  24. My priorities for the library (in approximately this order) are:
  25.  
  26. 1.  Bug fixes, of course!
  27. 2.  UNIX compatibility
  28. 3.  Synchronization with J. Bammi's GCC library
  29. 4.  Support for compilers other than GCC
  30. 5.  Frills (beautifying code, fixing ugly hacks, etc.)
  31. 6.  Documentation
  32.  
  33. If you notice a problem with the library but don't know how to fix it,
  34. please try to provide as much information as possible so that I can locate
  35. the problem (a short piece of code demonstrating the bug, for instance).
  36.  
  37. All top-level sources and all mntinc include files are now in UNIX carriage
  38. control format (LF line termination).  If your compiler/editor really wants
  39. carriage returns, you can convert files back to MS-DOS format (CR-LF line
  40. termination) using the program crlf.ttp supplied in the crlf/ subdirectory
  41. (source included).  I made this change because many of the programs I use
  42. get really confused with MS-DOS (TOS) style files.  Also, J. Bammi's GCC
  43. libs are maintained in the UNIX style, so converting everything will make
  44. synchronizing the two libraries easier.
  45.  
  46. If you're sending in patches for the library, please take into consideration
  47. the following words from Larry Wall, in the manual page for 'patch'.  It
  48. will make my life so much easier.
  49.  
  50.     NOTES FOR PATCH SENDERS
  51.         There are several things you should bear  in  mind  if  you  are
  52.         going to  be  sending out patches.  First, you can save people a
  53.         lot of grief by keeping a patchlevel.h file which is patched  to
  54.         increment  the  patch  level as the first diff in the patch file
  55.         you send out.  If you put a Prereq: line in with the  patch,  it
  56.         won't  let them apply patches out of order without some warning.
  57.         Second, make sure you've specified the filenames  right,  either
  58.         in a  context  diff  header, or with an Index: line.  If you are
  59.         patching something in a subdirectory, be sure to tell the  patch
  60.         user to specify a  -p switch as needed.  Third, you can create a
  61.         file by sending out a diff that compares a null file to the file
  62.         you want to create.  This will only work if the file you want to
  63.         create doesn't  exist  already in the target directory.  Fourth,
  64.         take care not to send  out  reversed  patches,  since  it  makes
  65.         people wonder  whether  they  already applied the patch.  Fifth,
  66.         while you may be able to get away with putting 582 diff listings
  67.         into one file, it is probably wiser  to  group  related  patches
  68.         into separate files in case something goes haywire.
  69.  
  70. Of course the notes about keeping a patchlevel.h file don't apply in this
  71. case, because I maintain the patchlev.h file for the library.  But please
  72. take note of the rest of it, especially the last sentence!
  73.  
  74. As of Patchlevel 31, the MiNT library no longer supports any version of 
  75. GCC before 2.0.
  76.  
  77. The GCC version of the MiNT library cannot be built on a TOS filesystem, due
  78. to name conflicts between several modules (for example, _udivmod.o and
  79. _udivmoddi4.o).  It should work on a cross-compiler or an ST with a
  80. filesystem such as minixfs.
  81.  
  82. My configuration, used to build the library on an extended filename
  83. V2 minixfs with gcc 2.4.5:
  84.   /mint/bin/mfsconf F: -s n -d n -x t -l n
  85.   UNIXMODE=bcu/rUxs
  86.  
  87. Special thanks go out to Jeff Weiner and the rest of the umich archive posse
  88. for letting me use terminator for the maintenance of the library.
  89.  
  90. May the source be with you.  Wish me luck...I'll need it!
  91.  
  92. Cheers,
  93. entropy
  94.  
  95. Eric's original readme file follows:
  96. ----------------------------------------------------------------------------
  97.  
  98. *NOTE*: to compile the library you will need the header files in mntinc25.zoo
  99.  
  100. ============================================================================
  101.  
  102. Here is mintlib, a library for gcc, Sozobon, Pure C, and Lattice C which
  103. produces programs usable under either MiNT or TOS (of course, some features,
  104. e.g. pipe(), are only available under MiNT). This version has been reasonably
  105. well tested under both TOS and MiNT, and with 16 and 32 bit integers, but no
  106. doubt bugs remain. Please report any that you find.
  107.  
  108. The main library has the GNU C version of the library, plus the common
  109. files. See the lattice, purec, and sozobon directories for compiler
  110. specific information.
  111.  
  112. The Lattice C support is definitely a bit rough around the edges (I may
  113. very well have messed up some of the patches, and I don't have Lattice to
  114. test it). Similarly, I can't test the Sozobon and Pure C support myself.
  115.  
  116. There are no docs ("Use the Source, Luke"), but most of the library should
  117. be pretty self-explanatory. If you know ANSI C and/or Posix, then most
  118. of the functions should be pretty clear to you.
  119.  
  120. MiNT specific features are active when the external variable __mint is
  121. non-zero; this variable is set automatically by the startup code in main.c.
  122.  
  123. Some things to watch out for:
  124.  
  125. (1) MiNT has a blocking fork(), i.e. the parent waits for the child to
  126.     relinquish its address space rather than continuing in parallel.
  127.     (Do NOT rely on this, though, since it will be corrected in a future
  128.     version of MiNT!)
  129. (2) Using the spawn functions instead of fork/exec means that your programs
  130.     will work under TOS as well as under MiNT. vfork() also works under
  131.     TOS now, so vfork/exec is another viable alternative.
  132. (3) The longjmp() code has a call to Psigreturn() embedded in it; this means
  133.     that most signal handlers will work without changes, but in some very
  134.     bizarre circumstances this could cause a problem (if the sig handler
  135.     longjmps *within* itself, and then returns, for example).
  136. (4) Under TOS, all terminal reads are assumed to come from the console
  137. (5) You'll note that there is only minimal support for UNIXMODE;
  138.     this is because MiNT 0.9 supports symlinks in the kernel.
  139. (6) A function call, tfork(), is provided to start a new thread of
  140.     execution in the same address space. The declaration is
  141.     int tfork( int (*func)(), long arg ).
  142.     A new process is started, which executes concurrently with the parent
  143.     process and in the same address space (but a different stack).
  144.     The child begins at the address in func, with the stack set up as though
  145.     the call (*func)(arg) was made (in fact, this call *is* made!).
  146.     The child will exit when func returns, with the exit status being the
  147.     return code of func. The parent continues to execute concurrently;
  148.     in the parent, the value returned from tfork() is the process id of the
  149.     child.
  150. (7) The library is not set up to handle multiple threads of execution in the
  151.     same address space, so you'll have to provide semaphores for critical
  152.     library calls (e.g. malloc) yourself if you have multiple threads.
  153.  
  154. The library is based on the gcc library that Jwahar Bammi and I put together.
  155. Lots of people have contributed to it, including (but not limited to):
  156.  
  157. Adrian Ashley, Jwahar Bammi, Scott Bigham, Kai-Uwe Bloem, Howard Chu,
  158. John R. Dunning, Doug Gwyn, Dave Gymer, Michael Hohmuth, Alan Hourihane,
  159. Alex Kiernan, Ulf Moeller, Allan Pratt, Arnold D. Robbins, Edgar Roeder,
  160. Rich Salz, Dale Schumacher, Andreas Schwab, Eric Smith, Henry Spencer,
  161. and Stephen Usher.
  162.